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Use of the Prefer Header Field in 
Web Distributed Authoring and Versioning (WebDAV) 


Abstract 


This document defines how the Prefer header field (RFC 7240) can be 
used by a Web Distributed Authoring and Versioning (WebDAV) client to 
request that certain behaviors be employed by a server while 
constructing a response to a request. Furthermore, it defines the 
new "depth-noroot" preference. 
This document updates RFC 7240. 
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Introduction 


[RFC7240] defines the Prefer header field and the "return=minimal" 
preference, which indicate that a client wishes for the server to 
return a minimal response to a successful request but states that 
what constitutes an appropriate minimal response is left solely to 
the discretion of the server. Section 2 of this specification 
defines precisely what is expected of a server when constructing 
minimal responses to successful WebDAV [RFC4918] requests. 


[RFC7240] also defines the "return=representation" preference, which 
indicates that a client wishes for the server to include an entity 
representing the current state of the resource in the response to a 
successful request. Section 3 of this specification makes 
recommendations on when this preference should be used by clients and 
extends its applicability to 412 (Precondition Failed) [RFC7232] 
responses. 


Finally, Section 4 of this specification defines the "depth-noroot" 
preference that can be used with HTTP methods that support the Depth 
header field. 


.1. Notational Conventions 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 


This document references XML element types in the "DAV:" [RFC4918], 
"urn:ietf:params:xml:ns:caldav" [RFC4791], and 
"urn:ietf:params:xml:ns:carddav" [RFC6352] namespaces outside of the 
context of an XML fragment. When doing so, the strings "DAV:", 
"CALDAV:", and "CARDDAV:" will be prepended to the XML element types, 
respectively. 


Reducing WebDAV Response Verbosity with "return=minimal" 


Some payload bodies in responses to WebDAV requests, such as 207 
(Multi-Status) [RFC4918] responses, Can be quite verbose or even 
unnecessary at times. This specification defines how the Prefer 
header field, in conjunction with its "return=minimal" preference, 
can be used by clients to reduce the verbosity of such responses by 
requesting that the server omit those portions of the response that 
can be inferred by their absence. 
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2.1. Minimal PROPFIND and REPORT Responses 
When a PROPFIND [RFC4918] request, or a REPORT [RFC3253] request 
whose report type results in a 207 (Multi-Status) response, contains 
a Prefer header field with a preference of "return=minimal", the 
server SHOULD omit all DAV:propstat XML elements containing a 
DAV:status XML element of value 404 (Not Found) [RFC7231] from the 
207 (Multi-Status) response. If the omission of such a DAV:propstat 
element would result in a DAV:response XML element containing zero 
DAV:propstat elements, the server MUST substitute one of the 
following in its place: 


o a DAV:propstat element consisting of an empty DAV:prop element and 
a DAV:status element of value 200 (OK) [RFC7231] 


o a DAV:status element of value 200 (OK) 

The following report types are candidates that could benefit from use 
of the "return=minimal" preference. NOTE: This list is not intended 
to be normative or exhaustive. 

o DAV:expand-property [RFC3253] 

o DAV:acl-principal-prop-set [RFC3744] 

o DAV:principal-property-search [RFC3744] 

o DAV:sync-collection [RFC6578] 

o CALDAV:calendar-query [RFC4791] 

o CALDAV:calendar-multiget [RFC4791] 


o CARDDAV:addressbook-query [RFC6352] 


o CARDDAV:addressbook-multiget [RFC6352] 


See Appendices B.1 and B.2 for examples. 
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2.2. Minimal PROPPATCH Response 
When a PROPPATCH [RFC4918] request contains a Prefer header field 
with a preference of "return=minimal", and all instructions are 
processed successfully, the server SHOULD return one of the following 
responses rather than a 207 (Multi-Status) response: 
o 204 (No Content) [RFC7231] 
o 200 (OK) [RFC7231] (preferably with a zero-length message body) 
See Appendix B.3 for examples. 


2.3. Minimal MKCALENDAR and MKCOL Responses 


Both the MKCALENDAR [RFC4791] and Extended MKCOL [RFC5689] 
specifications indicate that a server MAY return a message body in 


response to a successful request. This specification explicitly 
defines the intended behavior in the presence of the Prefer header 
field. 


When a MKCALENDAR or an extended MKCOL request contains a Prefer 
header field with a preference of "return=minimal", and the 
collection is created with all requested properties being set 
successfully, the server SHOULD return a 201 (Created) [RFC7231] 
response with an empty (zero-length) message body. 


Note that the rationale for requiring that a minimal success response 
have an empty body is twofold: 


o [RFC4791], Section 5.3.1 states: "If a response body for a 
successful request is included, it MUST be a CALDAV:mkcalendar- 
response XML element." 

o [RFC5689], Section 3 states: "When an empty response body is 
returned with a success request status code, the client can assume 


that all properties were set." 


See Appendix B.4 for examples. 
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Reducing WebDAV Roundtrips with "return=representation" 


[RFC7240] describes the "return=representation" preference as being 
intended to provide a means of optimizing communication between the 
client and server by eliminating the need for a subsequent GET 
request to retrieve the current representation of the resource 
following a modification. This preference is equally applicable to 
situations where the server itself modifies a resource, and where a 
resource has been modified by another client. 


1. Successful State-Changing Requests 


The state-changing methods PUT [RFC7231], COPY/MOVE [RFC4918], PATCH 
[RFC5789], and POST [RFC5995] can be used to create or update a 
resource. In some instances, such as with Calendaring Extensions to 
WebDAV (CalDAV) Scheduling [RFC6638], the created or updated resource 
representation may differ from the representation sent in the body of 
the request or from that referenced by the effective request URI. In 
cases where the client, upon receiving a 2xx (Successful) [RFC7231] 
response to its state-changing request, would normally issue a 
subsequent GET request to retrieve the current representation of the 
resource, the client can instead include a Prefer header field with 
the "return=representation" preference in the state-changing request. 


When a state-changing request contains a Prefer header field with a 
preference of "return=representation", and the resource is created or 
updated successfully, the server SHOULD include an entity 
representing the current state of the resource in the resulting 201 
(Created) or 200 (OK) [RFC7231] response. In addition to coalescing 
the create/update and retrieve operations into a single roundtrip, by 
returning the current representation of the resource in the response, 
the client will know that any changes to the resource were produced 
by the server rather than a concurrent client, thus providing a level 
of atomicity to the operation. 


See Appendix B.5 for examples. 


.2. Unsuccessful Conditional State-Changing Requests 


Frequently, clients using a state-changing method such as those 
listed above will make them conditional by including either an 
If-Match or an If-None-Match [RFC7232] header field in the request. 
This is done to prevent the client from accidentally overwriting a 
resource whose current state has been modified by another client 
acting in parallel. In cases where the client, upon receiving a 412 
(Precondition Failed) [RFC7232] response to its conditional state- 
changing request, would normally issue a subsequent GET request to 
retrieve the current representation of the resource, the client can 
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instead include a Prefer header field with the 
"return=representation" preference in the conditional state-changing 
request. 


When a conditional state-changing request contains a Prefer header 
field with a preference of "return=representation", and the specified 
condition evaluates to false, the server SHOULD include an entity 
representing the current state of the resource in the resulting 412 
(Precondition Failed) [RFC7232] response. 


See Appendix B.6 for examples. 
4. The "depth-noroot" Processing Preference 


The "depth-noroot" preference indicates that the client wishes for 
the server to exclude the target (root) resource from processing by 
the HTTP method and only apply the HTTP method to the target 
resource's subordinate resources. 


This preference is only intended to be used with HTTP methods whose 
definitions explicitly provide support for the Depth [RFC4918] header 
field. Furthermore, this preference only applies when the Depth 
header field has a value of "1" or "infinity" (either implicitly or 
explicitly). 


The "depth-noroot" preference MAY be used in conjunction with the 
"return=minimal" preference in a single request. 


See Appendix B.1 for examples. 
5. Security Considerations 
No new security considerations are introduced by use of the Prefer 


header field with WebDAV requests, beyond those discussed in 
[RFC7240] and those already inherent in those requests. 
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IANA Considerations 
.1. Preference Registration 


The following preference has been added to the HTTP Preferences 
Registry defined in Section 5.1 of [RFC7240]. 


Preference: depth-noroot 


Description: The "depth-noroot" preference indicates that the client 
wishes for the server to exclude the target (root) resource from 
processing by the HTTP method and only apply the HTTP method to 
the target resource’s subordinate resources. 


Reference: RFC 8144, Section 4 


Notes: This preference is only intended to be used with HTTP methods 
whose definitions explicitly provide support for the Depth 
[RFC4918] header field. Furthermore, this preference only applies 
when the Depth header field has a value of "1" or "infinity" 
(either implicitly or explicitly). 


.2. Method References 


The following methods have had their references updated in the "HTTP 
Method Registry" (http://www.iana.org/assignments/http-methods). 


+—------------ ooo ooo HZ + 

| Method | Safe | Idempotent | References 

| Name | | | 

Ho ooo +------------ +---------------------------------- + 

| MKCALENDAR | no | yes | RFC 4791, Section 5.3.1; RFC 

| | | | 8144, Section 2.3 | 
MKCOL | no yes | RFC 4918, Section 9.3; RFC 5689, | 

| Section 3; RFC 8144, Section 2.3 

| PROPFIND | yes | yes | RFC 4918, Section 9.1; RFC 8144, | 

| | | | Section 2.1 | 

| PROPPATCH | no | yes | RFC 4918, Section 9.2; RFC 8144, | 

| | | | Section 2.2 | 
REPORT yes yes RFC 3253, Section 3.6; RFC 8144, 

Section 2.1 
+—------------ ooo +------------ +---------------------------------- + 
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6.3. Status Code References 


The followi 


ng status code has had its references updated in the "HTTP 


Status Codes" registry (http://www.iana.org/assignments/http-status- 


codes). 


F 
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Appendix A. The Brief and Extended Depth Header Fields 


This document is based heavily on the Brief [MSDN.aa563501] and 
extended Depth [MSDN.aa563950] header fields. The behaviors 
described in Sections 2.1 and 2.2 are identical to those provided by 
the Brief header field when used with the PROPFIND [MSDN.aa580336] 
and PROPPATCH [MSDN.aa493854] methods, respectively. The behavior 
described in Section 4 is identical to that provided by the 
"1,noroot" [MSDN.aa563950] and "infinity,noroot" [MSDN.aa563950] 
Depth header field values. 


Client and server implementations that already support the Brief 
header field can add support for the "return=minimal" preference with 
nominal effort. 


If a server supporting the Prefer header field receives both the 
Brief and Prefer header fields in a request, clients can expect the 
server to ignore the Brief header field and only use the Prefer 
header field preferences. 


Appendix B. Examples 
B.1. PROPFIND 
B.1.1. Typical PROPFIND Request/Response with Depth:1 


This example tries to fetch one known and one unknown property from 
child resources. 


>> Request << 


PROPFIND /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 189 

Depth: 1 


<?xml version="1.0" encoding="UTF-8"?> 
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/"> 
<D:prop> 
<D:resourcetype/> 
<X: foobar/> 
</D:prop> 
</D:propfind> 


>> Response << 


HTTP/1.1 207 Multi-Status 
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Content-Type: application/xml; charset=utf-8 
Content-Length: 1722 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV:" 
xmlns:X="http://ns.example.com/foobar/"> 
<D:response> 
<D:href>/container/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X: foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
<D:response> 
<D:href>/container/work/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X: foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
<D:response> 
<D:href>/container/home/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
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<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X: foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
<D:response> 
<D:href>/container/foo.txt</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype/> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X: foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
</D:multistatus> 


B.1.2. Minimal PROPFIND Request/Response with Depth:1 


April 2017 


This example tries to fetch one known and one unknown property from 


child resources only. 
>> Request << 


PROPFIND /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 189 

Depth: 1 

Prefer: return=minimal, depth-noroot 


<?xml version="1.0" encoding="UTF-8"?> 


<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/"> 


<D:prop> 
<D:resourcetype/> 
<X: foobar/> 
</D:prop> 
</D:propfind> 
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>> Response << 


HTTP/1.1 207 Multi-Status 

Content-Type: application/xml; charset=utf-8 
Content-Length: 837 

Preference-Applied: return=minimal, depth-noroot 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV: "> 
<D:response> 
<D:href>/container/work/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
<D:response> 
<D:href>/container/home/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
<D:response> 
<D:href>/container/foo.txt</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype/> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</D:multistatus> 
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B.1.3. Minimal PROPFIND Request/Response with an Empty DAV:propstat 
Element 


This example tries to fetch an unknown property from a collection. 
>> Request << 


PROPFIND /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 166 

Prefer: return=minimal 


<?xml version="1.0" encoding="UTF-8"?> 
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/"> 
<D:prop> 
<X:foobar/> 
</D:prop> 
</D:propfind> 


>> Response << 


HTTP/1.1 207 Multi-Status 

Content-Type: application/xml; charset=utf-8 
Content-Length: 255 

Preference-Applied: return=minimal 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV: "> 
<D:response> 
<D:href>/container/</D:href> 
<D:propstat> 
<D:prop/> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</D:multistatus> 


B.2. REPORT 
B.2.1. Typical REPORT Request/Response 


This example tries to fetch an unknown property from several 
resources via the DAV:expand-property [RFC3253] REPORT type. 


>> Request << 


REPORT /dav/principals/ HTTP/1.1 
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Host: webdav.example.com 
Content-type: text/xml; charset=utf-8 
Content-length: 847 


<?xml version="1.0" encoding="utf-8"?> 
<D:expand-property xmlns:D="DAV:"> 
<D:property name="current-user-principal"> 
<D:property name="resourcetype"/> 
<D:property name="displayname"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
<D:property name="calendar-home-set" 
namespace="urn:ietf:params:xml:ns:caldav"> 
<D:property name="resourcetype"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
</D:property> 
<D:property name="addressbook-home-set" 
namespace="urn:ietf:params:xml:ns:carddav"> 
<D:property name="resourcetype"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
</D:property> 
</D:property> 
</D:expand-property> 


>> Response << 


HTTP/1.1 207 Multi-Status 
Content-Type: application/xml; charset=utf-8 
Content-Length: 2664 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV:" 
xmlns:C="urn:ietf:params:xml:ns:caldav" 
xmlns:R="urn:ietf:params:xml:ns:carddav" 
xmlns:X="http://ns.example.com/foobar"> 
<D:response> 
<D:href>/dav/principals/</D:href> 
<D:propstat> 
<D:prop> 
<D:current-user-principal> 
<D:response> 
<D:href>/dav/principals/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:principal/> 
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</D:resourcetype> 
<D:displayname>ken</D:displayname> 
<C:calendar-home-set> 
<D:response> 
<D:href>/dav/calendars/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X:foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
</C:calendar-home-set> 
<R:addressbook-home-set> 
<D:response> 
<D:href>/dav/addressbooks/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X:foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
</D:propstat> 
</D:response> 
</R:addressbook-home-set> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
<D:propstat> 
<D:prop> 
<X:foobar/> 
</D:prop> 
<D:status>HTTP/1.1 404 Not Found</D:status> 
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</D:propstat> 
</D:response> 
</D:current-user-principal> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 

</D:propstat> 
</D:response> 
</D:multistatus> 


B.2.2. Minimal REPORT Request/Response 


This example tries to fetch an unknown property from several 
resources via the DAV:expand-property [RFC3253] REPORT type. 


>> Request << 


REPORT /dav/principals/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 847 

Prefer: return=minimal 


<?xml version="1.0" encoding="utf-8"?> 
<D:expand-property xmlns:D="DAV: "> 
<D:property name="current-user-principal"> 
<D:property name="resourcetype"/> 
<D:property name="displayname"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
<D:property name="calendar-home-set" 
namespace="urn:ietf:params:xml:ns:caldav"> 
<D:property name="resourcetype"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
</D:property> 
<D:property name="addressbook-home-set" 
namespace="urn:ietf:params:xml:ns:carddav"> 
<D:property name="resourcetype"/> 
<D:property name="foobar" 
namespace="http://ns.example.com/foobar"/> 
</D:property> 
</D:property> 
</D:expand-property> 


>> Response << 


HTTP/1.1 207 Multi-Status 
Content-Type: application/xml; charset=utf-8 
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Content-Length: 1998 
Preference-Applied: return=minimal 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV:" 
xmlns:C="urn:ietf:params:xml:ns:caldav" 
xmlns:R="urn:ietf:params:xml:ns:carddav" 
xmlns:X="http://ns.example.com/foobar"> 
<D:response> 
<D:href>/dav/principals/</D:href> 
<D:propstat> 
<D:prop> 
<D:current-user-principal> 
<D:response> 
<D:href>/dav/principals/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:principal/> 
</D:resourcetype> 
<D:displayname>ken</D:displayname> 
<C:calendar-home-set> 
<D:response> 
<D:href>/dav/calendars/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</C:calendar-home-set> 
<R:addressbook-home-set> 
<D:response> 
<D:href>/dav/addressbooks/user/ken/</D:href> 
<D:propstat> 
<D:prop> 
<D:resourcetype> 
<D:collection/> 
</D:resourcetype> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</R:addressbook-home-set> 
</D:prop> 
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<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</D:current-user-principal> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 

</D:propstat> 
</D:response> 
</D:multistatus> 


B.3. PROPPATCH 


B.3.1. Typical PROPPATCH Request/Response 
>> Request << 


PROPPATCH /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 199 


<?xml version="1.0" encoding="utf-8"?> 
<D:propertyupdate xmlns:D="DAV:"> 
<D:set> 
<D:prop> 
<D:displayname>My Container</D:displayname> 
</D:prop> 
</D:set> 
</D:propertyupdate> 


>> Response << 


HTTP/1.1 207 Multi-Status 
Content-Type: application/xml; charset=utf-8 
Content-Length: 297 


<?xml version="1.0" encoding="utf-8"?> 
<D:multistatus xmlns:D="DAV: "> 
<D:response> 
<D:href>/container/</D:href> 
<D:propstat> 
<D:prop> 
<D:displayname/> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:response> 
</D:multistatus> 
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B.3.2. Minimal PROPPATCH Request/Response 
>> Request << 


PROPPATCH /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 199 

Prefer: return=minimal 


<?xml version="1.0" encoding="utf-8"?> 
<D:propertyupdate xmlns:D="DAV: "> 
<D:set> 
<D:prop> 
<D:displayname>My Container</D:displayname> 
</D:prop> 
</D:set> 
</D:propertyupdate> 


>> Response << 


HTTP/1.1 200 OK 
Content-Length: 0 
Preference-Applied: return=minimal 


B.4. MKCOL 
B.4.1. Verbose MKCOL Request/Response 
>> Request << 


MKCOL /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 181 


<?xml version="1.0" encoding="utf-8"?> 
<D:mkcol xmlns:D="DAV:"> 
<D:set> 
<D:prop> 
<D:displayname>My Container</D:displayname> 
</D:prop> 
</D:set> 
</D:mkcol> 


>> Response << 


HTTP/1.1 201 Created 
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Cache-Control: no-cache 
Content-Type: application/xml; charset=utf-8 
Content-Length: 224 


<?xml version="1.0" encoding="utf-8"?> 
<D:mkcol-response xmlns:D="DAV:"> 
<D:propstat> 
<D:prop> 
<D:displayname/> 
</D:prop> 
<D:status>HTTP/1.1 200 OK</D:status> 
</D:propstat> 
</D:mkcol-response> 


B.4.2. Minimal MKCOL Request/Response 
>> Request << 


MKCOL /container/ HTTP/1.1 

Host: webdav.example.com 

Content-Type: application/xml; charset=utf-8 
Content-Length: 181 

Prefer: return=minimal 


<?xml version="1.0" encoding="utf-8"?> 
<D:mkcol xmlns:D="DAV:"> 
<D:set> 
<D:prop> 
<D:displayname>My Container</D:displayname> 
</D:prop> 
</D:set> 
</D:mkcol> 


>> Response << 
HTTP/1.1 201 Created 
Cache-Control: no-cache 
Content-Length: 0 
Preference-Applied: return=minimal 
B.5. POST 
B.5.1. Typical Resource Creation and Retrieval via POST + GET 
Note that this request is not conditional because by using the POST 


[RFC5995] method, the client lets the server choose the resource URI, 
thereby guaranteeing that it will not modify an existing resource. 


Murchison Standards Track [Page 23] 


RFC 8144 Prefer Header Field in WebDAV April 2017 


>> Request << 


POST /container/work;add-member/ HTTP/1.1 
Host: caldav.example.com 

Content-Type: text/calendar; charset=utf-8 
Content-Length: 521 


BEGIN: VCALENDAR 

VERSION:2.0 

PRODID:-//Example Corp.//CalDAV Client//EN 

BEGIN: VEVENT 

UID:CD87465FA 

SEQUENCE: 0 

DTSTAMP :20120602T1852542Z 

DTSTART:20120602T160000Z 

DTEND:20120602T170000Z 

TRANSP : OPAQUE 

SUMMARY: Lunch 

ORGANIZER; CN="Ken Murchison":mailto:murch@example.com 

ATTENDEE; CN="Ken Murchison"; CUTYPE=INDIVIDUAL; PARTSTAT=ACCEPTED: 
mailto:murch@example.com 

ATTENDEE; CN="John Doe"; CUTYPE=INDIVIDUAL; PARTSTAT 
=NEEDS-ACTION; ROLE=REQ-PARTICIPANT; RSVP=TRUE: mailto: jdoe@ 
example.com 

END : VEVENT 

END : VCALENDAR 


>> Response << 
HTTP/1.1 201 Created 


Location: /container/work/abc.ics 
Content-Length: 0 


Note that the server did not include any validator header fields 
(e.g., ETag) in the response, signaling that the created 
representation differs from the representation sent in the body of 
the request. The client has to send a separate GET request to 
retrieve the current representation: 

>> Request << 


GET /container/work/abc.ics HTTP/1.1 
Host: caldav.example.com 


>> Response << 


HTTP/1.1 200 OK 
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Content-Type: text/calendar; charset=utf-8 
Content-Length: 541 

ETag: "nahduyejc" 

Schedule-Tag: "jfd84hgbcn" 


BEGIN: VCALENDAR 

VERSION:2.0 

PRODID:-//Example Corp.//CalDAV Server//EN 

BEGIN: VEVENT 

UID: CD87465FA 

SEQUENCE: 0 

DTSTAMP : 20120602T1853002 

DTSTART:20120602T1600002 

DTEND:20120602T170000Z 

TRANSP : OPAQUE 

SUMMARY : Lunch 

ORGANIZER; CN="Ken Murchison":mailto:murch@example.com 

ATTENDEE; CN="Ken Murchison"; CUTYPE=INDIVIDUAL; PARTSTAT=ACCEPTED: 
mailto:murch@example.com 

ATTENDEE; CN="John Doe"; CUTYPE=INDIVIDUAL; PARTSTAT 
=NEEDS-ACTION; ROLE=REQ-PARTICIPANT; RSVP=TRUE; SCHEDULE-STATUS= 
1.2:mailto: jdoe@example.com 

END: VEVENT 

END : VCALENDAR 


B.5.2. Streamlined Resource Creation and Retrieval via POST 


Note that this request is not conditional because by using the POST 
[RFC5995] method, the client lets the server choose the resource URI, 
thereby guaranteeing that it will not modify an existing resource. 


>> Request << 


POST /container/work; add-member/ HTTP/1.1 
Host: caldav.example.com 

Content-Type: text/calendar; charset=utf-8 
Content-Length: 521 

Prefer: return=representation 


BEGIN: VCALENDAR 
VERSION:2.0 

PRODID:-//Example Corp.//CalDAV Client//EN 
BEGIN: VEVENT 

UID:CD87465FA 

SEQUENCE: 0 

DTSTAMP:20120602T185254Z 
DTSTART:20120602T160000Z 
DTEND:20120602T170000Z 
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TRANSP : OPAQUE 

SUMMARY : Lunch 

ORGANIZER; CN="Ken Murchison":mailto:murch@example.com 

ATTENDEE; CN="Ken Murchison"; CUTYPE=INDIVIDUAL; PARTSTAT=ACCEPTED: 
mailto:murch@example.com 

ATTENDEE; CN="John Doe"; CUTYPE=INDIVIDUAL; PARTSTAT 

=NEEDS-ACTION; ROLE=REQ-PARTICIPANT; RSVP=TRUE: mailto: jdoe@ 
example.com 

END: VEVENT 

END : VCALENDAR 


>> Response << 


HTTP/1.1 201 Created 

Location: /container/work/abc.ics 
Content-Type: text/calendar; charset=utf-8 
Content-Length: 541 

Content-Location: /container/work/abc.ics 
ETag: "nahduyejc" 

Schedule-Tag: "jfd84hgbcn" 
Preference-Applied: return=representation 


BEGIN: VCALENDAR 

VERSION:2.0 

PRODID:-//Example Corp.//CalDAV Server//EN 

BEGIN: VEVENT 

UID:CD87465FA 

SEQUENCE: 0 

DTSTAMP : 20120602T1853002 

DTSTART:20120602T1600002 

DTEND:20120602T170000Z 

TRANSP : OPAQUE 

SUMMARY : Lunch 

ORGANIZER; CN="Ken Murchison":mailto:murch@example.com 

ATTENDEE; CN="Ken Murchison"; CUTYPE=INDIVIDUAL; PARTSTAT=ACCEPTED: 
mailto:murch@example.com 

ATTENDEE; CN="John Doe"; CUTYPE=INDIVIDUAL; PARTSTAT 
=NEEDS-ACTION; ROLE=REQ-PARTICIPANT; RSVP=TRUE; SCHEDULE-STATUS= 
1.2:mailto: jdoe@example.com 

END : VEVENT 

END : VCALENDAR 
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B.6. PUT 
B.6.1. Typical Conditional Resource Update Failure and Retrieval via 
PUT + GET 


>> Request << 

PUT /container/motd.txt HTTP/1.1 

Host: dav.example.com 

Content-Type: text/plain 

Content-Length: 69 

If-Match: "asd973" 

Either write something worth reading or do something worth writing. 


>> Response << 


HTTP/1.1 412 Precondition Failed 
Content-Length: 0 


The resource has been modified by another user agent (ETag mismatch) ; 
therefore, the client has to send a separate GET request to retrieve 
the current representation: 


>> Request << 


GET /container/motd.txt HTTP/1.1 
Host: dav.example.com 


>> Response << 

HTTP/1.1 200 OK 
Content-Type: text/plain 
Content-Length: 52 

ETag: "789sdas" 


An investment in knowledge pays the best interest. 


B.6.2. Streamlined Conditional Resource Update Failure and Retrieval 
via PUT 


>> Request << 
PUT /container/motd.txt HTTP/1.1 


Host: dav.example.com 
Content-Type: text/plain 
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Content-Length: 69 
If-Match: "asd973" 
Prefer: return=representation 


Either write something worth reading or do something worth writing. 
>> Response << 


HTTP/1.1 412 Precondition Failed 
Content-Type: text/plain 

Content-Length: 52 

Content-Location: /container/motd.txt 
ETag: "789sdas" 

Preference-Applied: return=representation 


An investment in knowledge pays the best interest. 
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